Skip to content

feat(skill-sources): trusted external skill sources — design, §13, formats, validator (Phase A)#677

Open
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:feat/trusted-external-skill-sources
Open

feat(skill-sources): trusted external skill sources — design, §13, formats, validator (Phase A)#677
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:feat/trusted-external-skill-sources

Conversation

@potiuk

@potiuk potiuk commented Jul 2, 2026

Copy link
Copy Markdown
Member

What this does

Introduces a mechanism to pull skills / skill-families from trusted external organizations and repositories, so a skill can live in another repo — a GitHub folder, an SVN/dist archive, or a git tag/branch — yet be adopted exactly like an in-tree skill: same magpie- symlink relay, same override layer, same eval binding. Where a skill directory would sit, a skills/<name>/source.md redirect pointer names a pinned, verified source the adopter has explicitly vouched for; the skill (with its evals and tests) is fetched into the gitignored snapshot and wired in.

This is Phase A — the design, the principle change, the formats, and the validator guardrails. It does not yet include the /magpie-setup fetch/lock/symlink wiring (that is Phase B; see below).

The one principle change — §13

PRINCIPLES.md §13 previously said catalogs may exist "for discovery, never for installation." This PR narrows that: installation is permitted only from a trusted source — an external org/repo the adopter has vouched for by committing its pin (method + URL + ref + verification anchor). Untrusted external sources, and the adapter/organization indexes, stay discovery-only. A trusted install obeys the same snapshot-plus-pin discipline the framework already uses for itself (gitignored snapshot, committed lock, verified deliberate fetch, no submodules, no unpinned/unverified auto-fetch).

Contents

  • docs/rfcs/RFC-AI-0006.md — the design: trust model + threat model.
  • docs/skill-sources/ — the source-descriptor and source.md pointer formats, plus a skills discovery registry (the skills counterpart to the adapter registry).
  • Three-layer trust: framework discovery registry → org-curated organizations/<org>/skill-sources.md → the adopter install gate <project-config>/skill-sources.md (nothing fetches unless listed there — final trust stays with the adopter).
  • skill-and-tool-validator now recognizes source.md pointer dirs (validates that source:/organization: resolve; suppresses the spurious eval-coverage advisory) and validates source descriptors. 13 new tests; full suite green.
  • Wired into extending.md, organizations/README, README, AGENTS.md, docs/index, and the org/project templates.

Phase B (follow-up, not in this PR)

  • The /magpie-setup skill-sources sub-action + .apache-magpie.sources.lock pair, folded into adopt / upgrade / verify (fetch, verify, pin, symlink, drift-detect).
  • A worked example pulled end-to-end.
  • A way for the source repos themselves to run the same kinds of evals and tests we run in Magpie, so a pulled skill is verifiable at its home.

Notes for review

Because it moves a bright line in PRINCIPLES.md, this is deliberately shaped as an RFC-first checkpoint — the mechanism is fully specified and enforced, but the invasive setup-skill surgery is held for Phase B so the trust model and §13 amendment can be reviewed first.

…rmats, validator (Phase A)

Introduce a mechanism to pull skills / skill-families from trusted
external organizations and repositories, so a skill can live in another
repo (a GitHub folder, an SVN/dist archive, or a git tag/branch) yet be
adopted exactly like an in-tree skill — same magpie- symlink relay, same
override layer, same eval binding.

Phase A (design + guardrails; no setup-skill fetch wiring yet):

- Amend PRINCIPLES §13 to permit installation from a *trusted* source the
  adopter has vouched for by committing its pin (method + URL + ref +
  verification anchor); untrusted external stays discovery-only. Reconcile
  the affected cross-references.
- RFC-AI-0006: trusted external skill sources — trust model + threat model.
- docs/skill-sources/: the source-descriptor and source.md redirect-pointer
  formats, plus a skills discovery registry (the skills counterpart to the
  adapter registry).
- Three-layer trust: framework discovery registry, org-curated
  organizations/<org>/skill-sources.md, and the adopter install gate
  <project-config>/skill-sources.md (nothing fetches unless listed there).
- skill-and-tool-validator: recognize skills/<name>/source.md pointer dirs
  and validate source descriptors; 13 new tests.
- Wire the mechanism into extending.md, organizations/README, README,
  AGENTS.md, docs/index, and the org/project templates.

Phase B (the /magpie-setup skill-sources fetch/lock/symlink wiring and a
worked example) follows in a later change.

@choo121600 choo121600 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me! I also think this is needed.
We should also think about how we'll manage these additional skills as the list grows, but I don't think that should block this change :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants